home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / DJGPP / BCCGRX12.ZIP / contrib / bcc2grx / readme < prev    next >
Text File  |  1993-07-23  |  19KB  |  479 lines
  1.  
  2.  BCC2GRX  -  Interfacing Borland based graphics programs to LIBGRX
  3.  Copyright (C) 1993  Hartmut Schirmer
  4.  
  5.  This library is free software; you can redistribute it and/or
  6.  modify it under the terms of the GNU Library General Public
  7.  License as published by the Free Software Foundation; either
  8.  version 2 of the License, or (at your option) any later version.
  9.  
  10.  This library is distributed in the hope that it will be useful,
  11.  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.  Library General Public License for more details.
  14.  
  15.  You should have received a copy of the GNU Library General Public
  16.  License along with this library; if not, write to the Free
  17.  Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18.  
  19. 1. Introduction and overview
  20. ------------------------------------------------------------------------------
  21.  
  22.    The BCC2GRX was created to allow users of DJGPP/LIBGRX to compile
  23.    graphics programs written for Borland's graphics interface. C code
  24.    can be directly compiled and linked with BCC2GRX. Pascal code has
  25.    to be converted by P2C.
  26.  
  27.  
  28.    Please note that BCC2GRX was designed for use with the DJGPP compiled
  29.    LIBGRX exclusively. The Borland-C++ LIBGRX isn't supported since
  30.    one can use the native BGI interface !
  31.  
  32.  
  33.    Using DJGPP/LIBGRX based graphics gives you some advantages :
  34.  
  35.       - 32 bit linear memory model
  36.       - high efficient C/C++/Objective-C compiler
  37.       - high resolution and high color graphics modes supported
  38.       - easy way to support new graphics adapters
  39.       - DJGPP, LIBGRX and BCC2GRX are free software
  40.       - most ported applications run faster
  41.  
  42.  
  43.    The actual BCC2GRX (v1.2) does only a few error checks since
  44.    it is assumed the progam was extensively tested before porting it
  45.    to DJGPP. BCC2GRX is not a convenient  platform to develop new BGI
  46.    programs. Of course you should use DJGPP's native LIBGRX in such
  47.    cases!
  48.  
  49.  
  50. 2. What do I need to use BCC2GRX ?  Where can I find it ?
  51. ------------------------------------------------------------------------------
  52.  
  53.    There are some things you need to use BCC2GRX :
  54.  
  55.      DJGPP    DJ Delorie's port ot GNU-C to MS-DOS              (djdev???.zip)
  56.      LIBGRX   Csaba Biegl's graphics library for BCC and DJGPP  (cbgrx???.zip)
  57.      BCC2GRX  of course                                         (bccgrx12.zip)
  58.      P2C      Dave Gillespie's Pascal to C converter (Optional) (hsp2c???.zip)
  59.      make     The BCC2GRX makefiles are tested with Borland
  60.           make 3.0/3.6 . GNUish make (3.58) may also be
  61.           used (check all makefiles to be set up correct!)
  62.  
  63.    These are the basic files. At least the DJGPP packages requires additional
  64.    files. Check the related documentation for more details.
  65.  
  66.    The home of all DJGPP related software is
  67.            omnigate.clarkson.edu (128.153.4.2)
  68.    in the directory
  69.            /pub/msdos/djgpp/ , /pub/msdos/djgpp/pub/
  70.  
  71.    The whole djgpp directory on omnigate seems to be mirrored eg. by
  72.        ftp.3com.com        (129.213.128.5) /mirrors/djgpp/
  73.        ftp.th-darmstadt.de (130.83.55.75)  /pub/machines/ms-dos/386/gcc/
  74.        rzserv3.rz.tu-bs.de (134.169.9.31)  /pub/pc/msdos/programmieren/djgpp/
  75.  
  76.    You should query an archie server to find a nearby server carrying
  77.    the files mentioned above.
  78.  
  79.  
  80.      ---------------------------------------------------------------
  81.      !                                                             !
  82.      ! ATTENTION:  BCC2GRX 1.2 needs LIBGRX Version 1.03 or newer. !
  83.      !                                                             !
  84.      ---------------------------------------------------------------
  85.  
  86.  
  87. 3. Installing BCC2GRX
  88. ------------------------------------------------------------------------------
  89.  
  90.   1. DJGPP is installed and tested
  91.  
  92.   2. Install the LIBGRX package and check it.
  93.  
  94.     a. Unpack the cbgrx???.zip
  95.     b. Set the environment variables
  96.       set GRXFONT=GCC/contrib/libgrx/fonts
  97.       set GO32=driver GCC/contrib/libgrx/drivers/stdvga.grn
  98.        where GCC is the home directory of djgpp. Use stdega.grn with EGA
  99.        cards. You shouldn't specify gw, gh or nc keywords. See DJGPP
  100.        and LIBGRX documentation for more detailed information.
  101.     c. goto GCC/contrib/libgrx/drivers and check our installation by
  102.        running
  103.           go32 modetest
  104.     d. if you succeded you can step on. You also may install a special
  105.        graphics driver supporting your hardware (run modetest again !).
  106.     e. Compile at least one test program (eg. test/test.c). If there are
  107.        problems, check the environment variables of DJGPP and LIBGRX again.
  108.  
  109.   3. Install the BCC2GRX and check it
  110.  
  111.     a. Unpack bccgrx12.zip
  112.     b. go to GCC/contrib/bcc2grx/test and issue the 'make' command.
  113.        (the makefile is set up for Borland Make 3.0, it may need some
  114.        changes with other make-s)
  115.     c. run bccbgi.exe
  116.  
  117.   4. Set up BCC2GRX for your own programs
  118.  
  119.     a. Copy GCC/contrib/bcc2grx/lib/libbcc.a to a directory in your
  120.        LIBRARY_PATH or add GCC/contrib/bcc2grx/lib to LIBRARY_PATH.
  121.     b. Copy GCC/contrib/bcc2grx/include *subdir* to a directory in
  122.        your C_INCLUDE_PATH or add GCC/contrib/bcc2grx/include to the
  123.        ???_INCLUDE_PATH environment variables.
  124.  
  125.   5. Install P2C and check it
  126.  
  127.     a. Unpack hsp2c???.zip
  128.     b. add set P2C_home=GCC/contrib/p2c/home to your environment
  129.     c. switch to GCC/contrib/p2c/examples and say make
  130.     d. run the test programs
  131.  
  132.   6. Set up P2C for BCC2GRX
  133.  
  134.     a. replace the 'graph' unit in GCC/contrib/p2c/home/turbo.imp
  135.        by GCC/contrib/bcc2grx/tp2bcc/p2c/graph.imp
  136.     b. Copy P2C.EXE to a directory in your PATH (eg. GCC/bin) or add
  137.        GCC/contrib/p2c/home to your PATH.
  138.     c. make sure that libp2c.a is found in your LIBRARY_PATH
  139.     d. Switch to GCC/contrib/bcc2grx/tp2bcc and build the bgidemo.exe
  140.        program by:
  141.      make cleanall
  142.      make
  143.     e. run bgidemo.exe
  144.  
  145.  
  146.   Now BCC2GRX should be installed. The last two steps (5.+6.) are
  147.   only required if Turbo-Pascal sources will be used with DJGPP.
  148.  
  149.   If you have serious problems, you should notice it on the djgpp
  150.   mailing list or contact me directly (see end of this text) !
  151.  
  152.  
  153. 4. Differences between BGI and BCC2GRX
  154. ------------------------------------------------------------------------------
  155.  
  156.    BCC2GRX is based on LIBGRX instead of the .bgi drivers. This fact
  157.    introduce some differences compared with the Borland GI. The (known)
  158.    differences are listed below.
  159.  
  160.  
  161.    - GNU-C is a 32 bit compiler. An int will take 4 bytes instead of
  162.      2 with Turbo-Pascal and BCC. If you need a 16 bit integer, change
  163.      the definition from int to short witch is 16 bit on either system.
  164.    - BLACK and WHITE are functions not constants with BCC2GRX. May cause
  165.      problems in switch () statements.
  166.    - BCC2GRX will not use .bgi drivers. Installing an user driver and
  167.      the register(far)bgidriver will always cause an error.
  168.    - registerfarbgifont() and registerbgifont() are the same. Both
  169.      take a void* to the character font (whole file with header !)
  170.    - initgraph()/detectgraph() work slightly different. See below for details.
  171.    - getmodenames() and other functions can be called before initgraph()
  172.    - character files won't be flushed at closegraph()
  173.    - NOT_PUT isn't supported.
  174.    - some constant's may differ in value (eg. VGA, ... )
  175.    - BCC2GRX's outtext() and outtextxy() do correct clipping
  176.    - some graphics primitives slightly differ in behaviour between BGI
  177.      and LIBGRX. Eg. the "saucer" in bccbgi.c putimage()/getimage() demo looks
  178.      different.
  179.    - the BCC2GRX header file is <libbcc.h> . You have to change the
  180.      #include statements since DJGPP defines an incompatible <graphics.h>.
  181.      Conditional compilation is a good way to handle this problem :
  182.      #ifdef __GNUC__
  183.      #  include <libbcc.h>
  184.      #else
  185.      #  include <graphics.h>
  186.      #endif
  187.  
  188.  
  189.  
  190. 5. Some useful internals of BCC2GRX
  191. ------------------------------------------------------------------------------
  192.  
  193.    Since LIBGRX provides a flexible and powerful set of graphics primitives,
  194.    some of the basic routines are defined within bccgrx.h using "__inline__
  195.    static" functions. GNU-C compiles these functions like macros but you can
  196.    refer to their address. There is one exeption to this rule : When compiling
  197.    code based on a pascal program, a macro is used for getaspectratio since
  198.    the pascal and C graphics interfaces use different calling types. You
  199.    should use src/whereis to find the file that implements a function.
  200.  
  201.    BGI has something called a 'viewport'. There are two very different behaviors
  202.    depending on the clipping flag:
  203.  
  204.      If clipping is on, one introduces something like a subscreen where
  205.      (nearly) all drawing operations are done.
  206.      Otherwise the origin of the drawing coordinate system is shifted from
  207.      the top left corner to some other point on screen.
  208.  
  209.    BCC2GRX allways adds the origin shift to all operations. If clipping is
  210.    requested, GrSetClipBox() is called and LIBGRX restricts drawing to the
  211.    selected subscreen.
  212.  
  213.    One may wonder why BCC2GRX has it's own drawpoly() function instead
  214.    of using the LIBGRX function. In BGI a polygon isn't really
  215.    a polygon but may be a union of several unconnected closed polygons.
  216.    In more detail:
  217.  
  218.      If the start point of a polygon is reached again, the next point
  219.      is the start point of a new polyon. No connection is drawn.
  220.  
  221.    So one may draw several closed polygons at once. I don't know whether
  222.    this behavior of the BGI is a bug or a feature, but BCC2GRX is
  223.    at least compatible ...
  224.  
  225.  
  226. 6. initgraph()/detectgraph()
  227. -----------------------------------------------------------------------------
  228.  
  229.   It's recommented to use something like the following code to
  230.   initialize the graphics interface :
  231.  
  232.    int gd, gm, err;
  233.    gd = DETECT;                         /* or detectgraph(&gd,&gm); */
  234.    initgraph(&gd,&gm,PATH_TO_CHR_FILES);
  235.    err = graphresult();
  236.    if (err != grOk) ...
  237.  
  238.   This code sets up the default graphics mode defined in the GO32
  239.   environment variable. If you need a special mode set by your program,
  240.   you should call it running a batch file:
  241.  
  242.      @echo off
  243.      set GO32 = <special_driver> <special_mode> ....
  244.      myprog.exe %1 %2 %3 ...
  245.  
  246.   This can not be done with every program due to DOS restrictions
  247.   (eg. maximum 9 parameters passed, environment space may exceed).
  248.   To overcome these problems, BCC2GRX uses a special graphics driver
  249.   called NATIVE_GRX. This new driver supports 3 abstract, one special
  250.   and of course all .grn driver modes. The following example shows the
  251.   usage of NATIVE_GRX :
  252.  
  253.       int gd, gm, err;
  254.     #ifdef __GNUC__
  255.       gd = NATIVE_GRX;
  256.       gm = <mode>;
  257.     #else
  258.       /* BCC stuff */
  259.     #endif
  260.       initgraph(&gd,&gm,PATH_TO_CHR_FILES);
  261.       err = graphresult();
  262.       if (err != grOk) ...
  263.  
  264.   where <mode> can take to following values :
  265.  
  266.      GRX_DEFAULT_GRAPHICS                (same as DETECT)
  267.      GRX_BIGGEST_NONINTERLACED_GRAPHICS  (see LIBGRX documentation for details)
  268.      GRX_BIGGEST_GRAPHICS                (see LIBGRX documentation for details)
  269.      GRX_BGI_EMULATION                   (see below)
  270.      GRX_BGI_EMULATION+1 .. ?            (Graphics modes from .grn drivers)
  271.  
  272.   The GRX_BGI_EMULATION mode is the most flexible one and needs to be
  273.   initialized before calling initgraph(). The mean idea is to select the
  274.   graphics resolution and colors by calling
  275.  
  276.       void set_BGI_mode(int *graphdriver, int *graphmode);
  277.   or
  278.       void set_BGI_mode_whc(int *graphdriver, int *graphmode,
  279.                 int width, int height, int colors);
  280.  
  281.   Lets have a look at some examples. If you need eg. 640x480x16 standard
  282.   VGA mode, use something like
  283.  
  284.        gd = VGA; gm = VGAHI;
  285.      #ifdef __GNUC__
  286.        set_BGI_mode( &gd, &gm);
  287.      #endif
  288.        initgraph( &gd, &gm, "");
  289.  
  290.   Non standard resolutions (eg. 800x600x256) use set_BGI_mode_whc() :
  291.  
  292.      #ifdef __GNUC__
  293.        set_BGI_mode_whc( &gd, &gm 800, 600, 256);
  294.      #else
  295.        /* BGI stuff invoking a high resolution mode */
  296.      #endif
  297.        initgraph( &gd, &gm, "");
  298.  
  299.  
  300.   The BCC2GRX requests to desired resolution by a
  301.     GrSetMode( GR_width_height_color_graphics, ...)
  302.   function call. If there is no such mode in the current driver, a related
  303.   one will be used by LIBGRX. If you program needs a special resolution
  304.   (say eg. Hercules 720x348) you should check getmaxx() and getmaxy() after
  305.   initgraph() .
  306.  
  307.   Please note that
  308.  
  309.     - set_BGI_mode(HERCMONO, HERCMONOHI) uses 720x350x16 on VGA cards,
  310.     - all drivers != NATIVE_GRX behave like DETECT with BCC2GRX,
  311.     - set_BGI_mode[_whc]() sets up local variables used by initgraph() and
  312.       setgraphmode(). You may change the resolution after initgraph() done
  313.       by
  314.          gd = DETECT;
  315.          initgraph(&gd, &gm, "");
  316.          /* Default graphics mode */
  317.          ....
  318.        #ifdef __GNUC__
  319.          set_BGI_mode_whc(&gd, &gm, 1024, 768, 256);
  320.        #else
  321.          /* BGI stuff to set up 1024x768x256 mode */
  322.          gm = ... ;
  323.        #endif
  324.          setgraphmode( gm);
  325.          /* Now in 1024x768x256 mode */
  326.  
  327.     - closegraph() doesn't free any memory allocated for vector fonts. So
  328.       you can't switch to a second (different) set of fonts. Every font will
  329.       be loaded once and stay in (virtual) memory until the program terminates.
  330.       If this behaviour doesn't work with your program (eg. something like a
  331.       font editor) or you get short of memory loading hundreds of fonts,
  332.       please tell me about.
  333.  
  334.  
  335. 7. Using fonts
  336. ------------------------------------------------------------------------------
  337.  
  338.    The BCC2GRX v1.2 or newer can link vector fonts into the .exe file.
  339.    The standard fonts are in the libgrx.a :
  340.  
  341.        _bold_font, _euro_font, _goth_font, _lcom_font
  342.        _litt_font, _sans_font, _scri_font, _simp_font
  343.        _trip_font, _tscr_font
  344.  
  345.    Call registerbgifont() to enable font usage :
  346.  
  347.        registerbgifont( &_bold_font);
  348.        registerbgifont( &_euro_font);
  349.        registerbgifont( &_goth_font);
  350.        registerbgifont( &_lcom_font);
  351.        registerbgifont( &_litt_font);
  352.        registerbgifont( &_sans_font);
  353.        registerbgifont( &_scri_font);
  354.        registerbgifont( &_simp_font);
  355.        registerbgifont( &_trip_font);
  356.        registerbgifont( &_tscr_font);
  357.  
  358.    Of course you can also link non standard fonts :
  359.  
  360.        - copy the .chr file(s) to bcc2grx/chr
  361.        - say nonbgi <font_name>      (font_name: 4 letters, no extension)
  362.        - copy the <font_name>.o to your source files
  363.        - add
  364.            extern int _<font_name>_font;
  365.            registerbgifont( &_<font_name>_font);
  366.          to your source
  367.        - add it to the linker command line
  368.           ( gcc -o test test.o <font_name>.o -lbcc -lgrx )
  369.  
  370.    The actual BCC2GRX handels the 11 standard and up to 10 user fonts. If you
  371.    need mode user fonts, you should change the definition of LastUserFont in
  372.    bccgrx06.c !
  373.  
  374.  
  375.    Starting with BCC2GRX V1.2 you can also use the LIBGRX bitmapped fonts.
  376.    Just get a font handle and set the new text style. Eg. you may want to
  377.    use the 8x16 VGA font in high resolution graphics:
  378.  
  379.       font_handle = installuserfont( "@:pc8x16.fnt");
  380.       settextstyle( font_handle, HORIZ_DIR, 1);
  381.  
  382.    See test/ttext.c for more examples.
  383.  
  384.  
  385. 8. What's new in this release ?
  386. ------------------------------------------------------------------------------
  387.  
  388.    - makefiles prepeared for GNUish make
  389.    - set_BGI_mode() / set_BGI_mode_whc() stuff
  390.    - Linkable vector fonts
  391.    - nearly complete error checking
  392.  
  393.    The complete list of changes or new features in the current version of
  394.    BCC2GRX can be found in src/changes .
  395.  
  396.  
  397. 9. Short description of BCC2GRX files
  398. ------------------------------------------------------------------------------
  399.  
  400. The BCC2GRX library contains the following files :
  401.  
  402. README                 This file.
  403. MAKEFILE               General makefile  (Borland make 3.0 tested)
  404. INCLUDE/               Global header files
  405. INCLUDE/P2C/           Global header files needed in P2C converted stuff
  406. SRC/                   Source code of BCC2GRX
  407. TP2BCC/                Pascal test files, p2c resources
  408. TEST/                  C test files
  409. LIB/                   BCC2GRX library
  410. CHR/                   Borland font files
  411. COPYING.LIB            The license conditions of the BCC2GRX distribution
  412.  
  413. TP2BCC.H               Definitions needed in P2C converted code
  414. TASTEN.H               Definitions of keycodes returned by getkey(). May be
  415.                set up for a german keyboard.
  416. BGIEXT.H               Functions and data not defined by BGI
  417. LIBBCC.H               Standard include files when using BCC2GRX
  418.                (Includes  BGIEXT.H, BCCGRX.H, GRX.H, delay)
  419. TP_PORT.H              Definitions of useful Borland-like functions ( random
  420.                number generator, readkey, ...)
  421. BCCGRX.H               Declaration of standard BGI functions, ...
  422.  
  423. LIBBCC.A               This is BCC2GRX. May be copied to your DJGPP
  424.                library directory. (gcc 2.4.1 compiled)
  425.  
  426. BCCGRX.C               Basic interface file. Holds global data and the
  427.                mode switching code.
  428. BCCGRX??.C             Graphics primitives.
  429. BGIEXT??.C             New graphic routines useful with BCC2GRX and the
  430.                Borland C compiler.
  431. DELAY.S                Source of a Borland like delay procedure.
  432. RAND_TP.C              Source of a Borland like random number generator
  433. READKEY.C              Source of a Turbo-Pascal like readkey function
  434.  
  435. BCCBGI.C               This is an extended copy of the BGIDEMO.C that
  436.                comes with BCC 3.0.
  437. HTMEXT.INC             Extended demo routines, included by BCCBGI.C.
  438.  
  439. P2CRC                  P2C resource file needed to translate Pascal BGI
  440.                into BCC BGI code.
  441. GRAPH.IMP              Definitions exported by graph.tpu, should replace the
  442.                unit 'graph' in TURBO.IMP that comes with P2C (1.20)
  443. BGIDEMO.PAS            Corrected source code of the BGIDEMO.PAS that comes
  444.                with TP 6.0
  445.  
  446. -----------------------------------------------------------------------------
  447.  
  448. DJGPP mailing list :
  449.  
  450.     There are two DJGPP related lists :
  451.  
  452.       DJGPP@sun.soe.clarkson.edu
  453.       DJGPP-announce@sun.soe.clarkson.edu
  454.  
  455.     Send an email containing only 'help' to
  456.  
  457.       LISTSERV@sun.soe.clarkson.edu
  458.  
  459.     for more information.
  460.  
  461. -----------------------------------------------------------------------------
  462. Contact :                Hartmut Schirmer
  463.              Feldstrasse 118
  464.           D-2300 Kiel 1
  465.              Germany
  466.  
  467.  
  468.     NOTE : Please use
  469.              Hartmut Schirmer
  470.              Feldstrasse 118
  471.          D-24105 Kiel
  472.              Germany
  473.  
  474.        after July 1 1993 !!
  475.  
  476.  
  477.     email : PHC27@rz.uni-kiel.dbp.de   (subject to change)
  478.  
  479.